chore(feature-flags): Keep the runtime clients safe across fork() - #767

Stack. This is #762, split into four PRs for review. Merge them in order; after each merge I'll rebase the next one onto main.

1. chore(feature-flags): Parse and evaluate flag configurations locally #764 Configuration and evaluation
2. feat(feature-flags): Evaluate feature flags locally with a polling runtime client #765 Sync runtime client
3. feat(feature-flags): Add an async feature flags runtime client #766 Async runtime client
4. chore(feature-flags): Keep the runtime clients safe across fork() #767 Fork safety ← this PR

Description

A runtime client created before a fork, as in an app gunicorn loads with --preload, can now be used in each worker.

• Default HTTP client. With the SDK's default HTTP client, the sync client polls through an httpx client of its own instead of the WorkOSClient's. A forked child drops the inherited client without closing it, because its sockets belong to the parent. The child resumes polling on new connections the first time the runtime client is used there.

• When the child doesn't poll. Some things a child can't safely replace:

  • a caller-supplied HTTP client that the parent already sent requests through, from the runtime client, any other SDK call, or another WorkOS client given the same HTTP client (requests are recorded against the HTTP client itself);
  • an AsyncWorkOSClient used in the parent, whose connections belong to the parent's event loop.

  In those cases, start() and refresh() raise, wait_until_ready() raises right away if there's no configuration, and the client keeps serving its last configuration. A client that was polling logs a warning the first time it's used.

• macOS. On macOS a child never polls. Once a process has created an HTTP client, a child it forks segfaults in the system trust store when it opens a new TLS connection. So a preloaded app still boots on a Mac, start() there logs one warning, naming gunicorn's post_fork hook as the fix, and returns instead of raising. refresh() still raises, and wait_until_ready() raises right away if there's no configuration. The client serves its bootstrap or last configuration, otherwise the caller's defaults.

• Rebuilding in the child. The child rebuilds locks, events and the poller thread through os.register_at_fork. A client that fails to rebuild is logged and doesn't stop the others.

Where to look:

1. _sync.py: _reinitialize_after_fork and _before_use.
2. _transport.py: fork_blocker and _httpx_client.
3. _async.py: _reinitialize_after_fork.
4. The README's "Processes" paragraph.

How I checked it:

• test_fork.py forks a real child in a subprocess for each case. It polls a local HTTP server that records each request's TCP port, and checks that the child polls on its own connections or not at all. The cases are:

  • a sync client that was polling with the default HTTP client: it resumes on new connections, and any read restarts it;
  • a caller-supplied HTTP client: unused, it starts in the child; used by the runtime client, by another SDK call, or by another WorkOS client sharing it, it doesn't poll;
  • an async client: unused, it starts in the child; used by the runtime client, by another SDK call, or by another AsyncWorkOSClient sharing its HTTP client, it doesn't poll;
  • macOS: it doesn't poll, and start() warns once instead of raising, with and without a bootstrap.

  It also checks that an async client's close() returns in the child. The tests pass on macOS here, and CI runs them on Linux.

• I reproduced each Greptile finding on feat(feature-flags): Evaluate feature flags locally with a polling runtime client #762 and on this PR before fixing it:

  • an async close() in a child hung;
  • a sync child polled through the parent's used client;
  • an async child failed with Event loop is closed;
  • with two WorkOS clients sharing one HTTP client, a child polled over the parent's connections;
  • a custom backend that can't be hashed made the fork hook raise and stop rebuilding the other clients.

• On this Mac, I forked a real child after creating a WorkOSClient. Its first new TLS connection segfaulted inside SecTrustEvaluate, with or without OBJC_DISABLE_INITIALIZE_FORK_SAFETY=YES. With this change, a child that calls start() and wait_until_ready() logs one warning, serves its bootstrap, makes no network attempt and exits cleanly; without a bootstrap, wait_until_ready() raises at once instead of hanging.

• The full feature flags runtime lab passed against this branch before the macOS start() change: 87 of 87 checks, and the bridge suite 5 of 5.

• nox -s ci passes locally: 3,743 tests.

Documentation

Does this require changes to the WorkOS Docs? E.g. the API Reference or code snippets need updates.

[x] Yes

The docs PR noted on #765 should cover forked workers.

🤖 Generated with Claude Code